feat(feature-flags): Evaluate feature flags locally with a polling runtime client - #765

Stack. This is #762, split into four PRs for review. Merge them in order; after each merge I'll rebase the next one onto main.

1. chore(feature-flags): Parse and evaluate flag configurations locally #764 Configuration and evaluation
2. feat(feature-flags): Evaluate feature flags locally with a polling runtime client #765 Sync runtime client ← this PR
3. feat(feature-flags): Add an async feature flags runtime client #766 Async runtime client
4. chore(feature-flags): Keep the runtime clients safe across fork() #767 Fork safety

Description

FeatureFlagsRuntimeClient polls GET /sdk/feature-flags?payload_version=2 on a daemon thread and keeps the configuration from #764 in memory. It evaluates flags locally, with no request per check.

flags = workos.create_feature_flags_runtime_client()
flags.start()
flags.wait_until_ready(timeout=5)
flags.is_enabled("new-checkout", {"user": "user_123", "organization": "org_123"})

• Failures.
  • A failed poll keeps the last good configuration and backs off exponentially.
  • A 429's Retry-After is honored up to 60 seconds, by retries inside a refresh and before the next poll.
  • Transient failures are retried within one refresh, up to the client's max_retries and within request_timeout.
  • A 401 stops polling for good.
• Time budget. Each refresh has a total budget. The transport streams the response and gives every network wait only the time left, so a refresh ends within request_timeout plus at most one read of a body that stalls. A copy of those timeouts still gets the time left, never None, in case a custom transport or a later httpcore copies them instead of reading each phase as it starts.
• Also included: bootstrap, on_change, on_error and on_status listeners, status, get_flag(), and a manual refresh() that works without start().
• Listeners run after the refresh lock is released, one batch at a time and in refresh order, so a listener can call refresh() itself. An async def listener raises TypeError when it's registered, since nothing on the sync client would await it.
• close() stops polling, and nothing a refresh still in flight does changes the configuration or status after it returns. Every caller waits for the poller, including concurrent ones.
• Change events follow .NET: one on_change per refresh that installs a new configuration, including the first load.
• v1 payloads fail the refresh and keep the previous configuration.

Where to look, in order:

1. _core.py: state, evaluation and listeners.
2. _sync.py: _poll_forever, _refresh_locked and _drain.
3. _transport.py: the time budget.
4. _policy.py: backoff and retry decisions.

Not in this PR: fork handling comes in #767. Until then, the README says to create the runtime client in each worker after forking. Merge #765 through #767 before the next release PR, so the first release includes fork handling.

How I checked it:

• I ran it in our feature flags runtime lab, side by side with the Node SDK, against the same fixture responses. All 80 side-by-side checks pass: 40 for Python, 40 for Node. They cover:

  • rule order, contexts, disabled flags, unknown rules and non-boolean values;
  • bootstrap;
  • 401, 403 and 500 responses;
  • slow responses and v1 responses.

  The lab's asyncio checks need feat(feature-flags): Add an async feature flags runtime client #766.

• test_transport.py sends the poll to a real local HTTP server. That includes one server that stalls before answering and one that drips the body a byte at a time. In both cases the refresh ends within its budget. Its other tests copy the timeouts every common way on a fake clock and check each phase gets the time left; on the code before that change they got None.

• nox -s ci passes locally: 3,693 tests.

Documentation

Does this require changes to the WorkOS Docs? E.g. the API Reference or code snippets need updates.

[x] Yes

The feature flags SDK docs describe the runtime client as Node only. A docs PR adding Python, covering both clients, is still to do.

🤖 Generated with Claude Code